A.C.E. 2

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 2 / ACE CD 2.iso / FILES / UTILS / JACOSUB.LHA / JACOsub / documentation / Overview.doc < prev next >

Wrap

Text File | 1995-03-19 | 23.9 KB | 522 lines

JACOsub: video titling software for professionals version 2.1 Timed Script Editor and Player A Product from Unicorn Research Corporation This document provides an overview of the JACOsub software package (features, installation, compatibility, script conversion, and product support). Be sure to read the product support section concerning bug reports, if you don't read anything else. Other documentation files in this package are: JACOsub.doc - Information on actually running the program. JScripts.doc - Detailed information on the JACOsub script format specification. ARexx.doc - Covers ARexx communications with JACOsub. QuickRef.doc - Quick reference for script commands and directives. FAQ - Some Frequently Asked Questions, with answers. Register.doc - Information about registering the software. WHAT IS JACOsub? ================ JACOsub is a program designed for displaying timed sequences of titles and graphics over a video. Professional-quality output and flexibility have been the primary goals since the program's inception. It was originally written for the Japanese Animation Club or Orlando (JACO) to lay English subtitles over Japanese-language films and television shows. The program has spread and grown in popularity due to its extremely flexible script format, clean multi-buffered title transitions, and other features described in the next section. The development of JACOsub has been primarily user-driven. Most of the program's more interesting features exist because users suggested them. Because of the valuable input given by so many people, JACOsub has become an exceptionally powerful program while retaining its initial simplicity at the same time. SPECIAL FEATURES OF JACOsub =========================== * Non-sequential events. Title time ranges may overlap. * Display graphic images with the text. Time ranges for graphic images may overlap also. Graphics (pictures or brushes) may be positioned anywhere on the screen. If you do not need to generate text over graphics, you can load IFF pictures independently of JACOsub's display. JACOsub supports AGA graphics! Loading IFF files requires AmigaDOS 2.0 or higher. * Handles all kinds of time units: SMPTE, 1/100 second units, etc. * Extremely flexible timing script file format, allowing comments, blank lines, text directives, and global configuration commands. Scripts can be as simple or as complex as you want. Scripts may even include other scripts, so you don't have to re-time parts that you use over and over again. * Complete script-based control over text position, margins, font, style, colors, palettes, backshadow, word-wrapping, and justification. You can even generate anti-aliased outlines and shadows on mono-color text. Text appearance can be controlled through line directives or with C-style escape code inside the subtitle text. * Support for 3rd-party script formats: TurboTitle (.tts), Phoenix Japanimation Society (.pjs), generic (.tim), Panimator (.pan), and also Subtitle (.sub) format. The Jconvert utility is provided to convert all these formats to JACOsub (.js) format. JACOsub can read directly all but .pan and .sub scripts without prior conversion. * Multi video buffering and page switching. Many titling programs create a display in a hidden buffer, then blit it to the visible foreground at the proper time. But the duration of a multi-bitplane blit can be up to 3 video frames. This can cause disconcerting "flashing" effects. Both TurboTitle and PJS's software have this problem. JACOsub has a better way: It uses video-page switching rather than blitting, to move displays to the foreground. Images appear during the vertical CRT blanking interval. Blitting is only used between hidden buffers, never on the visible display. JACOsub uses 4 video buffers by default. * You can make time shift and drift adjustments "on the fly" while your script is playing. * Fully integrated script editor. If needed, video titles may be positioned graphically with the mouse. * ARexx support -- other programs can issue commands to JACOsub, and your JACOsub scripts can execute ARexx scripts while playing. You can even edit scripts trhough ARexx. * You can control the Digital Creations SuperGen genlock faders directly from your script! GVP and Video Toaster genlock fades may be controlled indirectly through ARexx scripts. * Robust compiler diagnostics for tracking down problems in your scripts. Author: Alex Matulich 1515 Jefferson Davis Hwy #820 Arlington, VA 22202-3311 (703) 413-0215 email: matulich_a@SEAA.NAVSEA.NAVY.MIL Beta Testers: Fred A. Leggett III (JACO), Daric Kozlowski (JACO) Tom Perry (Phoenix Japanimation Society) Noel Gamboa (Operation X) Robert Lowrey (Central Anime) Roger Ang, Jacob Ellis, Dave Fleming, Mike Harlock, Tommy Hwang, Ed Sum Compiler: SAS Amiga C/C++ 6.51 Computer: Amiga 1000 (never say die!) with WorkBench 2.1 AmigaDOS 2.04 ROM hacked in, 2M FAST, 512K CHIP, 30MB C-Ltd HD INSTALLATION ============ After extracting the archive you should have these files (an "I" in the first column indicates that the file has an icon (.info file) associated with it). I README.1st Quick install and run instructions I CHANGES.TXT List of improvements and bug fixes I InstallFonts Installs JACOsub's fonts into fonts: I JACOsub The timing script compiler & player JACOsub.cfg Empty config file to replace older ones I jconvert Conversion utility for 3rd-party scripts proglogo.bbm Initial graphic that appears in the editor I documentation (subdirectory) I Overview.doc You're reading it now I JACOsub.doc Documentation on operating the software I JScripts.doc JACOsub Script file format specification I ARexx.doc ARexx communications documentation I Register.doc Shareware registration instructions I FAQ Frequently-Asked Questions, with answers fonts (subdirectory) JACOsub.font A few high-quality video titling fonts JACOsub (subdirectory) 18e 18-pixel height monochrome font for clock 29.4C 29-pixel international color outline font 32.4C 32-pixel international outline/shadow font 36.4C 36-pixel international outline/shadow font JACOsub_superhires.font Titling font for use in SUPERHIRES mode JACOsub_superhires (subdirectory) 36.4C SUPERHIRES color outline font rexx (subdirectory) abortplay.jsrx Demo of ABORTPLAY ARexx command begintime.jsrx Demo of BEGINTIME ARexx command loadscript.jsrx Demo of LOADSCRIPT ARexx command playsetup.jsrx Demo of PLAYSETUP ARexx command playstart.jsrx Demo of PLAYSTART ARexx command quit.jsrx Demo of QUIT ARexx command savescript.jsrx Demo of SAVESCRIPT Arexx command screentoback.jsrx Demo of SCREENTOBACK ARexx command screentofront.jsrx Demo of SCREENTOFRONT ARexx command etc... ...and various others described in ARexx.doc I scripts (subdirectory) I demo.js Demonstration script for JACOsub I idemo.js Secondary script included by demo.js I JACO.bbm Graphic logo; IFF brush used by demo.js All you need to do to install the software after you extract the archive, is copy the supplied fonts to your fonts: directory. To do this, simply double-click on the "InstallFonts" icon, or enter these commands from the JACOsub directory at a Shell prompt: copy fonts fonts: all ;copy the supplied fonts delete fonts all ;delete the fonts directory created by the ;archive extraction. THE JACOsub FONTS MUST BE IN YOUR FONTS: DIRECTORY PRIOR TO RUNNING THE PROGRAM FOR THE FIRST TIME. The fonts get updated and improved periodically, so you should always re-install them whenever you get a new version of this software. If you have a SuperGen genlock, you need to make sure that your LIBS: directory contains supergen.library and copinit.library. If they are missing, you won't be able to control your SuperGen from JACOsub scripts. Before you run the program, you should be aware of some issues concerning different versions of AmigaDOS: AmigaDOS 1.2: You will not be able to run JACOsub with color fonts. If you boot up with a 1.3 disk using 1.2 Kickstart, you may have better luck. In any case, upgrade to 1.3 or 2.0 as soon as you can. Your libs: directory should contain req.library. There are no guarantees that the program will work under AmigaDOS 1.2. AmigaDOS 1.3: You will need to load a Colortext driver prior to running JACOsub. A good Colortext driver by InterActive Softworks is supplied with Deluxe Paint IV or Calligrapher. If you don't load this driver, you will see only single-colored characters while JACOsub runs. >> DO NOT USE ColorTextWedge 1.2 (supplied with TurboTitle) -- it forces all text into JAM2 mode which chops up fonts having overlapping dropshadows (such as the supplied JACOsub font). Also, your libs: directory should contain req.library, though it's not required. >> Under 1.3, JACOsub's IFF capabilities will be unavailable to you. AmigaDOS 2.0 users do not need any special driver -- it's built into 2.0. You don't need req.library, but your libs: directory should contain the AmigaDOS asl.library. It's a good idea to patch it with the reqtools.library patch utility if you have it. You will have JACOsub's IFF capabilities, but you will be unable to load files using AGA modes. AmigaDOS 3.0 and above: Should behave the same as AmigaDOS 2.0, except that you can load IFF files that use AGA graphic modes. Now you're ready to begin. Just click twice on JACOsub's program icon, or type "run jacosub" from a Shell prompt. Refer to JACOsub.doc for more detailed information on operating the program. INTERACTIONS WITH OTHER SOFTWARE ================================ Directory Opus 4.0: DO NOT use JACOsub with Directory Opus 4.0! This version of Directory Opus has some known problems that will cause you much grief if you try to run JACOsub with it. We recommend you avoid directory utilities altogether when running JACOsub! EPU, PowerPacker, and other filesystem compression utilities: File compressors used to give JACOsub problems before version 1.9 if the compressor was set to report the compressed sizes of files, rather than the original, uncompressed size. This no longer matters; disk compressors should cause no trouble. Genlocks: In general, be sure all video sources are off, and your genlock is not trying to gain a lock on anything, when you boot up your computer. Genlocks affect the Amiga's internal clocking, and can cause timing instabilities if you power everything up in the wrong order. GVP genlocks seem to be especially fussy about how they are brought online. GVP users: load IFF files with JACOsub at your own risk. There is an incompatibility between the GVP and the AmigaDOS IFF loader routines. SuperGen users should have at least version 2.0 of the supergen.library and copinit.library. See the GENLOCK SUPPORT section below for details. Text editors: Some users have reported that certain text editors, when run in the background while JACOsub is running, will mess up script timing. We have had no problems with TxED. Other users have reported no problems with CED. In any case, it is probably a good idea to shut down unnecessary tasks before running ANY timing-critical application such as JACOsub. req.library: You should have either asl.library or req.library in your libs: directory. The program should still work fine without these, however. Warning: I have observed instances of req.library trashing memory location $00000078 (in the zero-page memory area) which is dangerous for AmigaDOS. If your computer crashes right before a file requester should appear, the fault is with req.library, not JACOsub. JACOsub will use asl.library under AmigaDOS 2.0 and above. reqtools.library: Highly recommended! The patch utility that comes with reqtools.library patches req.library, asl.library, and arp.library to use features in reqtools.library. It fixes the problem with req.library described above. Reqtools.library makes your Amiga (and JACOsub) significantly more pleasant to use. GENLOCK SUPPORT =============== SuperGen (Digital Creations) -------- JACOsub allows your scripts to control the faders on a SuperGen genlock. You need to have supergen.library and copinit.library in your LIBS: directory to take advantage of this feature. These libraries are available from the libs directory of your Digital Creations SuperGen software disk. SUPERGEN.LIBRARY VERSIONS LESS THAN 2.0 WILL NOT WORK WITH JACOsub. If your SuperGen library is too old, your fades will results in jittery dissolves. Update your SuperGen library as soon as possible. JACOsub will not assume control over the SuperGen until it must execute a fader command. From that point on, the genlock will be under software control until the script play terminates, and then control will be returned to manual mode. Warning! DO NOT BOOT UP YOUR AMIGA WITH A SIGNAL PRESENT ON THE SUPERGEN'S VIDEO INPUT!! Doing so will adversly affect the Amiga's system clock, which will cause your scripts to run erratically or much too fast! See the G directive in the Script Format Specification documentation JScripts.doc, for information on controlling the SuperGen. Other genlocks will be supported as software and documentation becomes available to the author. GVP Genlock (Great Valley Products) ----------- Dissolves with the GVP G-Lock must be controlled through ARexx. JACOsub will look for the ARexx script "gvpfade.jsrx" in the current directory, a "rexx" subdirectory under the current directory, and in REXX:, and copy the script to ram:glfade.jsrx for faster execution. This script is currently not provided. See the file ARexx.doc for specifications of this script. If you create such a script, please send it to us! If you have a GVP Genlock, PLAY SCRIPTS THAT LOAD IFF GRAPHICS AT YOUR OWN RISK! Your Amiga WILL VERY LIKELY crash! Great Valley Products says that the normal AmigaDOS IFF loading routines cause problems when the GVP is in operation. Great Valley Products has their own proprietary IFF loader routines available, but JACOsub does not support them yet. JACOsub uses AmigaDOS 2.0 iffparse.library with the standard IFF loader from the ROM Kernel Devices manual. Set GENLOCK to GVP in your JACOsub.cfg file; this will cause a compile-time warning to be issued if a script attempts to load an IFF file. In the future, the GVP setting will enable true GVP support. Video Toaster (NewTek) ------------- The first paragraph under "GVP Genlock) above applies to the Video Toaster also, only the script should be named "toasterfade.jsrx." General Information ------------------- Warning! The genlock may sometimes show things that do not appear on the RGB display. Some examples we discovered: A vertical line appears on the right edge of genlocked display, but not on the RGB display. Solution that worked for us: Be sure the horizontal screen size is a multiple of 32, such as 640, 672, or 704. Digital Creations tells us that this line won't appear on your videotape, but we suspect they're talking about a different phenomenon. Little pieces of characters from the left side of the screen appear on the right edge. This happens when a character's kern setting causes the left edge of the screen to clip off a pixel or two, as in the 'W' and 't' of the 36-pixel JACOsub font. You can see this when you run the demo script after changing the left margin to 0% by inserting the line #HL0 at the top of the script. Solution: Use the HL1 directive instead of HL0, to provide a few pixels of margin space. This will keep kerned characters from going past the left edge of the display. AREXX SUPPORT ============= If you have ARexx, JACOsub will open an ARexx port called 'JACOsub'. You can use a different program (such as SCALA for example) to issue a number of commands to JACOsub, and you can have JACOsub execute ARexx scripts while a JACOsub script is playing. For more information, see the file ARexx.doc. SCRIPT CONVERSION UTILITY ========================= Although JACOsub can read directly TurboTitle and Phoenix scripts, they won't be able to use many of JACOsub's advanced features. If you need text with non-sequential, overlapping time ranges, or if you need to control the positioning or attributes of the text, or if you want to play a Panimator script with JACOsub, you must convert the script to the JACOsub script format. You don't *have* to convert .pjs or .tts scripts to JACOsub format if you need only to adjust text style or color (green italics, etc.). For these operations, you can insert style and color codes directly into your text, and still retain compatibility with your other timing software. Your other software won't use these codes (they'll get displayed on the screen instead). See the Script File Format Specification documentation JScripts.doc for descriptions of the possible codes that you can use. If you need to convert to JACOsub, it's very simple. The Shell command is jconvert [-v[erbose]] scriptname1.ext [scriptname2.ext] ... where .ext can be: .tts (TurboTitle) .pjs (Phoenix Japanimation Society) .tim (Generic) .pan (Panimator) .sub (Subtitle) The optional -v or -verbose switch causes jconvert to echo its output to the screen as it writes the new file. To run jconvert from Workbench, you can click on its icon twice. A file requester will appear, allowing you to select a file to convert. If you have SCRIPTPATH specified in JACOsub.cfg, jconvert will use this as the starting directory for the file requester. Or, if you need to convert multiple scripts, you may multiply select your script icons (clicking while holding down the SHIFT key) ending with a double-click on the jconvert icon. Jconvert will read in the script, and write out a new script file called scriptname.js which will be in JACOsub format. Then you can modify scriptname.js to take advantage of JACOsub's advanced features. Source code for jconvert is available separately. It should work for any computer or operating system. If you need it, write to the author, check your local BBS, or call Anime Central BBS (see information at the end of this document). NOTICE: We recommend that you let JACOsub try to read your script PRIOR to converting it with jconvert, because JACOsub can inform you of potential problems with your script, but jconvert cannot. Jconvert does not analyze your scripts; it simply converts them blindly. The only exception is when converting TurboTitle scripts, jconvert will correct overlapping time ranges by shortening the previous line's end time to be equal to the current line's start time. JACOsub SCRIPT FILE FORMAT SPECIFICATION ======================================== See the textfile JScripts.doc for a complete description of the JACOsub script file format. About those 3rd-party file formats ---------------------------------- Robert Jenks, the author of TurboTitle, made an excellent suggestion in his documentation, that the TurboTitle format should be adopted as a standard for future software. JACOsub is compatible with TurboTitle files, but the TurboTitle format was just not flexible enough for our needs. We needed to use SMPTE time units, we needed to control color, style, and positioning of text, we needed to insert comments in the script and inside the text, and we needed no restrictions on how time events were sequenced. (We also needed something that displayed text faster and more cleanly, but that had nothing to do with the file format.) The preceding paragraph is not meant to be critical of Mr. Jenks' work. TurboTitle was a fine program for its time, and it served to provide some inspirational influence for JACOsub. TurboTitle is still a good program for timing scripts. We feel that the JACOsub script file format is the most flexible yet developed. Scripts can be as simple as TurboTitle scripts, containing only timing numbers and text, or you can go all out with global commands and complex directives. We will follow the example of TurboTitle's author, and ask that the JACOsub format be adopted as a standard for future titling software products. The format is flexible enough to evolve and grow, so if you have suggestions for improvements or changes, please let us know. And especially, if you want JACOsub to support another file format, tell us the specifications and we'll try to work it into either the program itself or the jconvert utility. SHAREWARE REGISTRATION / COMMERCIAL LICENSING ============================================= Please refer to the file register.doc. LEGAL DISCLAIMER ================ (Shamelessly adapted from Haventree's EasyFlow documentation) We don't claim JACOsub is good for anything -- if you think it is, great, but it's up to you to decide. If JACOsub doesn't work: tough. If you lose a million because JACOsub messes up, it's you that's out the million, not us. If you don't like this disclaimer: tough. We reserve the right to do the absolute minimum provided by law, up to and including nothing! This is basically the same disclaimer that comes with all other software packages, but ours is in plain English and theirs is in Legalese. Additional disclaimer: The author will attempt to update the software as needed, but is not obligated to do so. SUPPORT, TECHNICAL QUESTIONS, SUGGESTIONS, BUG REPORTS ====================================================== You can contact the author, Alex Matulich, at the address at the beginning of this file. Alex may be reached via email, using the following addresses: Internet: matulich_a@SEAA.NAVSEA.NAVY.MIL alex@bilver.oau.org (should automatically forward) Alex.Matulich@animece.oau.org (last resort) Fidonet: 1:363/140 or 1:363/137, name "Alex Matulich" (last resort) Support BBS: Anime Central 407-645-2241, N-8-1, 14,400 baud max (v.32bis), Fidonet address 1:363/137. The latest version of JACOsub, and timed scripts contributed by JACOsub users, are in the JACOsub Support file area. Please do not ask questions of the Sysop regarding JACOsub. Instead please direct all questions to Alex Matulich. IMPORTANT: WHEN SUBMITTING A BUG REPORT, BE SURE THE PROBLEM IS REPEATABLE AND SPECIFY THE CONDITIONS UNDER WHICH THE PROBLEM OCCURRED. Too many people report problems like "the program crashed when I tried to play my script" with no other information. This kind of report helps nobody! What version of JACOsub? What version of AmigaDOS? What kind of computer? What were you doing prior to noticing the problem? Can you reproduce it and isolate it enough for ME to be able to do the same? If you encounter a problem, try to isolate it. If the problem is being caused by something in your script, send the author a small sample script with your bug report that demonstrates the problem. Try running the program on another machine -- if it runs fine on another machine, try to determine what's different about your setup that's causing the trouble. And try to describe the bug as completely as possible in your report. If you're still reading this far, thank you for using JACOsub. End of Overview.doc.